<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>glob manual page - Tcl Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl Commands</a> <small>&gt;</small> glob</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="glob.htm#M2" NAME="L658">NAME</A>
<DL><DD>glob &mdash; Return names of files that match patterns</DD></DL>
<DD><A HREF="glob.htm#M3" NAME="L659">SYNOPSIS</A>
<DL>
</DL>
<DD><A HREF="glob.htm#M4" NAME="L660">DESCRIPTION</A>
<DD><A HREF="glob.htm#M5" NAME="L661">OPTIONS</A>
<DL class="options">
<DD><A HREF="glob.htm#M6" NAME="L662"><B>-directory</B> <I>directory</I></A>
<DD><A HREF="glob.htm#M7" NAME="L663"><B>-join</B></A>
<DD><A HREF="glob.htm#M8" NAME="L664"><B>-nocomplain</B></A>
<DD><A HREF="glob.htm#M9" NAME="L665"><B>-path</B> <I>pathPrefix</I></A>
<DD><A HREF="glob.htm#M10" NAME="L666"><B>-tails</B></A>
<DD><A HREF="glob.htm#M11" NAME="L667"><B>-types</B> <I>typeList</I></A>
<DD><A HREF="glob.htm#M12" NAME="L668"><B>--</B></A>
</DL>
<DD><A HREF="glob.htm#M13" NAME="L669">GLOBBING PATTERNS</A>
<DL class="globbing patterns">
<DD><A HREF="glob.htm#M14" NAME="L670"><B>?</B></A>
<DD><A HREF="glob.htm#M15" NAME="L671"><B>*</B></A>
<DD><A HREF="glob.htm#M16" NAME="L672"><B>[</B><I>chars</I><B>]</B></A>
<DD><A HREF="glob.htm#M17" NAME="L673"><B>&#92;</B><I>x</I></A>
<DD><A HREF="glob.htm#M18" NAME="L674"><B>{</B><I>a</I><B>,</B><I>b</I><B>,</B><I>...</I>}</A>
</DL>
<DD><A HREF="glob.htm#M19" NAME="L675">WINDOWS PORTABILITY ISSUES</A>
<DD><A HREF="glob.htm#M20" NAME="L676">EXAMPLES</A>
<DD><A HREF="glob.htm#M21" NAME="L677">SEE ALSO</A>
<DD><A HREF="glob.htm#M22" NAME="L678">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
glob &mdash; Return names of files that match patterns
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>glob </B>?<I>switches</I>? ?<I>pattern ...</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
This command performs file name
&ldquo;globbing&rdquo;
in a fashion similar to
the csh shell or bash shell.
It returns a list of the files whose names match any
of the <I>pattern</I> arguments. No particular order is guaranteed
in the list, so if a sorted list is required the caller should use
<B><A HREF="../TclCmd/lsort.htm">lsort</A></B>.
<H4><A NAME="M5">OPTIONS</A></H4>
If the initial arguments to <B>glob</B> start with <B>-</B> then
they are treated as switches. The following switches are
currently supported:
<P>
<DL class="options">
<DT><A NAME="M6"><B>-directory</B> <I>directory</I></A><DD>
Search for files which match the given patterns starting in the given
<I>directory</I>. This allows searching of directories whose name
contains glob-sensitive characters without the need to quote such
characters explicitly. This option may not be used in conjunction with
<B>-path</B>, which is used to allow searching for complete file paths
whose names may contain glob-sensitive characters.
<P><DT><A NAME="M7"><B>-join</B></A><DD>
The remaining pattern arguments, after option processing, are treated
as a single pattern obtained by joining the arguments with directory
separators.
<P><DT><A NAME="M8"><B>-nocomplain</B></A><DD>
Allows an empty list to be returned without error; without this
switch an error is returned if the result list would be empty.
<P><DT><A NAME="M9"><B>-path</B> <I>pathPrefix</I></A><DD>
Search for files with the given <I>pathPrefix</I> where the rest of the name
matches the given patterns. This allows searching for files with names
similar to a given file (as opposed to a directory) even when the names
contain glob-sensitive
characters. This option may not be used in conjunction with
<B>-directory</B>. For example, to find all files with the same root name
as $path, but differing extensions, you should use
&ldquo;<B>glob -path [file rootname $path] .*</B>&rdquo;
which will work even if <B>$path</B> contains
numerous glob-sensitive characters.
<P><DT><A NAME="M10"><B>-tails</B></A><DD>
Only return the part of each file found which follows the last directory
named in any <B>-directory</B> or <B>-path</B> path specification.
Thus
&ldquo;<B>glob -tails -directory $dir *</B>&rdquo;
is equivalent to
&ldquo;<B>set pwd [pwd]; cd $dir; glob *; cd $pwd</B>&rdquo;.
For <B>-path</B> specifications, the returned names will include the last
path segment, so
&ldquo;<B>glob -tails -path [file rootname ~/foo.tex] .*</B>&rdquo;
will return paths like <B>foo.aux foo.bib foo.tex</B> etc.
<P><DT><A NAME="M11"><B>-types</B> <I>typeList</I></A><DD>
Only list files or directories which match <I>typeList</I>, where the items
in the list have two forms. The first form is like the -type option of
the Unix find command:
<I>b</I> (block special file),
<I>c</I> (character special file),
<I>d</I> (directory),
<I>f</I> (plain file),
<I>l</I> (symbolic link),
<I>p</I> (named pipe),
or <I>s</I> (socket), where multiple types may be specified in the list.
<B>Glob</B> will return all files which match at least one of the types given.
Note that symbolic links will be returned both if <B>-types l</B> is given,
or if the target of a link matches the requested type. So, a link to
a directory will be returned if <B>-types d</B> was specified.
<P>
The second form specifies types where all the types given must match.
These are <I>r</I>, <I>w</I>, <I>x</I> as file permissions, and
<I>readonly</I>, <I>hidden</I> as special permission cases. On the
Macintosh, MacOS types and creators are also supported, where any item
which is four characters long is assumed to be a MacOS type
(e.g. <B><A HREF="../TkCmd/text.htm">TEXT</A></B>). Items which are of the form <I>{macintosh type XXXX}</I>
or <I>{macintosh creator XXXX}</I> will match types or creators
respectively. Unrecognized types, or specifications of multiple MacOS
types/creators will signal an error.
<P>
The two forms may be mixed, so <B>-types {d f r w}</B> will find all
regular files OR directories that have both read AND write permissions.
The following are equivalent:
<P>
<PRE><B>glob -type d *</B>
<B>glob */</B></PRE>
<P>except that the first case doesn't return the trailing
&ldquo;/&rdquo;
and is more platform independent.
<P><DT><A NAME="M12"><B>--</B></A><DD>
Marks the end of switches. The argument following this one will
be treated as a <I>pattern</I> even if it starts with a <B>-</B>.
<P></DL>
<H4><A NAME="M13">GLOBBING PATTERNS</A></H4>
The <I>pattern</I> arguments may contain any of the following
special characters, which are a superset of those supported by
<B><A HREF="../TclCmd/string.htm">string match</A></B>:
<P>
<DL class="globbing patterns">
<DT><A NAME="M14"><B>?</B></A><DD>
Matches any single character.
<P><DT><A NAME="M15"><B>*</B></A><DD>
Matches any sequence of zero or more characters.
<P><DT><A NAME="M16"><B>[</B><I>chars</I><B>]</B></A><DD>
Matches any single character in <I>chars</I>. If <I>chars</I>
contains a sequence of the form <I>a</I><B>-</B><I>b</I> then any
character between <I>a</I> and <I>b</I> (inclusive) will match.
<P><DT><A NAME="M17"><B>&#92;</B><I>x</I></A><DD>
Matches the character <I>x</I>.
<P><DT><A NAME="M18"><B>{</B><I>a</I><B>,</B><I>b</I><B>,</B><I>...</I>}</A><DD>
Matches any of the sub-patterns <I>a</I>, <I>b</I>, etc.
<P></DL>
<P>
On Unix, as with csh, a
&ldquo;.&rdquo;&nbsp;
at the beginning of a file's name or just after a
&ldquo;/&rdquo;
must be matched explicitly or with a {} construct, unless the
<B>-types hidden</B> flag is given (since
&ldquo;.&rdquo;&nbsp;
at the beginning of a file's name indicates that it is hidden). On
other platforms, files beginning with a
&ldquo;.&rdquo;&nbsp;
are handled no differently to any others, except the special directories
&ldquo;.&rdquo;&nbsp;
and
&ldquo;..&rdquo;&nbsp;
which must be matched explicitly (this is to avoid a recursive pattern like
&ldquo;glob -join * * * *&rdquo;
from recursing up the directory hierarchy as well as down). In addition, all
&ldquo;/&rdquo;
characters must be matched explicitly.
<P>
If the first character in a <I>pattern</I> is
&ldquo;~&rdquo;
then it refers to the home directory for the user whose name follows the
&ldquo;~&rdquo;.
If the
&ldquo;~&rdquo;
is followed immediately by
&ldquo;/&rdquo;
then the value of the HOME environment variable is used.
<P>
The <B>glob</B> command differs from csh globbing in two ways.
First, it does not sort its result list (use the <B><A HREF="../TclCmd/lsort.htm">lsort</A></B>
command if you want the list sorted).
Second, <B>glob</B> only returns the names of files that actually
exist; in csh no check for existence is made unless a pattern
contains a ?, *, or [] construct.
<P>
When the <B>glob</B> command returns relative paths whose filenames
start with a tilde
&ldquo;~&rdquo;
(for example through <B>glob *</B> or <B>glob -tails</B>, the returned
list will not quote the tilde with
&ldquo;./&rdquo;.
This means care must be taken if those names are later to
be used with <B><A HREF="../TclCmd/file.htm">file join</A></B>, to avoid them being interpreted as
absolute paths pointing to a given user's home directory.
<H3><A NAME="M19">WINDOWS PORTABILITY ISSUES</A></H3>
For Windows UNC names, the servername and sharename components of the path
may not contain ?, *, or [] constructs. On Windows NT, if <I>pattern</I> is
of the form
&ldquo;<B>~</B><I>username</I><B>@</B><I>domain</I>&rdquo;,
it refers to the home
directory of the user whose account information resides on the specified NT
domain server. Otherwise, user account information is obtained from
the local computer.
<P>
Since the backslash character has a special meaning to the glob
command, glob patterns containing Windows style path separators need
special care. The pattern
&ldquo;<I>C:&#92;&#92;foo&#92;&#92;*</I>&rdquo;
is interpreted as
&ldquo;<I>C:&#92;foo&#92;*</I>&rdquo;
where
&ldquo;<I>&#92;f</I>&rdquo;
will match the single character
&ldquo;<I>f</I>&rdquo;
and
&ldquo;<I>&#92;*</I>&rdquo;
will match the single character
&ldquo;<I>*</I>&rdquo;
and will not be
interpreted as a wildcard character. One solution to this problem is
to use the Unix style forward slash as a path separator. Windows style
paths can be converted to Unix style paths with the command
&ldquo;<B><A HREF="../TclCmd/file.htm">file join</A></B> <B>$path</B>&rdquo;
or
&ldquo;<B><A HREF="../TclCmd/file.htm">file normalize</A></B> <B>$path</B>&rdquo;.
<H3><A NAME="M20">EXAMPLES</A></H3>
Find all the Tcl files in the current directory:
<P>
<PRE><B>glob</B> *.tcl</PRE>
<P>
Find all the Tcl files in the user's home directory, irrespective of
what the current directory is:
<P>
<PRE><B>glob</B> -directory ~ *.tcl</PRE>
<P>
Find all subdirectories of the current directory:
<P>
<PRE><B>glob</B> -type d *</PRE>
<P>
Find all files whose name contains an
&ldquo;a&rdquo;,
a
&ldquo;b&rdquo;
or the sequence
&ldquo;cde&rdquo;:
<P>
<PRE><B>glob</B> -type f *{a,b,cde}*</PRE>
<H3><A NAME="M21">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/file.htm">file</A></B>
<H3><A NAME="M22">KEYWORDS</A></H3>
<A href="../Keywords/E.htm#exist">exist</A>, <A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/G.htm#glob">glob</A>, <A href="../Keywords/P.htm#pattern">pattern</A>
<div class="copy">Copyright &copy; 1993 The Regents of the University of California.
<BR>Copyright &copy; 1994-1996 Sun Microsystems, Inc.
</div>
</BODY></HTML>
